#
# misc.hlp ---		Online help strings for pfe,
#			miscellaneous nice words
# (duz 16Sep94)
#

: COLD ( ... x --- ) [FIG]
re-initializes the forth system. Closes all files, cleans the
dictionary and all stacks.


: .LINE ( line blk --- ) [FIG]
displays the specified line of the specified block. No spaces before,
one space after, no newlines are output.


: CSP ( --- a-addr ) [FIG]
variable used for error checking during compilation. See !CSP and
?CSP.


: !CSP ( --- ) [FIG]
stores the actual stack pointer into the variable CSP. The data stack
is used as control flow stack during compilation. Use !CSP in words
that switch to compiling state. See ?CSP.


: ?CSP ( --- ) [FIG]
compares the actual stack pointer with the contents of the variable
CSP (compiler security pointer). An error is detected when both are
not equal and -22 THROW (control structure mismatch) is executed.
When the actual data stack pointer equals the value in CSP nothing
happens. Use ?CSP in words that switch from compiling back to
interpreting state to be sure all opened control structures are
properly closed. See !CSP and ?PAIRS.


: ?COMP ( --- ) [FIG]
when state is not compiling, then -14 THROW is executed which unless
caught issues the message "interpreting a compile-only word" and
aborts.


: ?EXEC ( --- ) [FIG]
when state is not interpreting, then -29 THROW is executed which
unless caught issues the message "compiler nesting" and aborts.


: ?FILE ( ior --- )
takes an io-result as most words from the files word set produce.
Nothing happens if the io-result is zero for "no error". If ior is
non-zero ?FILE executes `-256 SWAP - THROW' which unless caught issues
an appropriate error message and aborts. The error message wording
stems from a call to strerror().


: ?LOADING ( --- ) [FIG]
nothing happens when executed while a block is loaded. Otherwise
executes -35 THROW which unless caught issues the message "invalid
block number" and aborts. Typical use in words that do relative
loading like --> or +THRU.


: ?PAIRS ( n1 n2 --- ) [FIG]
usage only when compiling.
If n1 and n2 are equal nothing happens. Otherwise executes -22 THROW
which unless caught issues the message "control structure mismatch"
and aborts. See ?CSP.


: ?STACK ( --- ) [FIG]
if one of the three stacks (data-, return- and floating point-stack)
over- oder underflows then ?STACK executes the appropriate THROW:
	-3	data stack overflow
	-4	data stack underflow
	-5	return stack overflow
	-6	return stack underflow
	-44	floating point stack overflow
	-45	floating point stack underflow
which unless caught issues the above message and aborts.


: TOGGLE ( c-addr char --- ) [FIG]
stores at c-addr: the result of an exclusive or between the character
at c-addr and char. Thus toggles all bits at c-addr that are set in
char.


: LATEST ( --- c-addr ) [FIG]
returns the address of the count byte of the name of the topmost word
in the compilation word-list. If the compilation word list hasn't
changed since the last defintion and if no words have been deleted
from the dictionary since the last definition then this is the most
recently defined word. In traditional singly linked dictionaries,
LATEST can be defined as `CURRENT @ @', in pfe it's `CURRENT @ TOPMOST
@'.  See: LAST, CURRENT, TOPMOST, WL-HASH.


: SMUDGE ( --- )
Sets bit 5 in the count byte of the most recent definition's
name. This prevents the definition from being found in dictionary
searches before it is properly finished, e.g. after CREATE in `:'.
See UNSMUDGE, LAST.


: UNSMUDGE ( --- )
Clears bit 5 in the count byte of the most recent definition's name.
This allows the definition to be found in dictionary searches. Use
when a defintion is finished, e.g. in `;'. See SMUDGE, LAST.


: UD.R ( ud n --- )

displays the unsigned double number ud right-adjusted in a field of
width of at least n. No trailing space is displayed.


: UD. ( ud --- )
displays the unsigned double number ud with a trailing space.


: .NAME ( c-addr --- )
c-addr is the address of the count byte of a defintion's name. Prints
the name of the definition with a trailing space.


: -ROLL ( x(n) x(n-1) ... x1 x0 n --- x0 x(n) x(n-1) ... x1 )
after removing n from the stack, rotates n+1 items on the top of the
stack such that the topmost element becomes the (n+1)st element.


: R>DROP ( R: x --- )
removes the topmost element from the return stack.


: DUP>R ( x --- x ) ( R: --- x )
places a copy of the top element of the data stack on the return
stack.


: RANDOM ( n1 --- n2 )
returns a random number in the range [0, n1-1].


: SRAND ( n --- )
initializes the random number generator with a seed n.


: UNDER+ ( n1 n2 --- n1+n2 n2 )
adds the top element to the second without removing the top element.
Same as `SWAP OVER + SWAP'.


: +TO ( x "<spaces>name" --- )
adds x to the contents of the VALUE or local variable "name".
See TO, VALUE, LOCALS|.


: BUILD-ARRAY ( n1 n2 ... nX X --- n )
stores n1 through nX into the dictionary and returns the product
n = n1*n2*...*nX.
n1...nX are upper bounds for indices of a multi-dimensional array.
n is the resulting total number of elements. See ACCESS-ARRAY.


: ACCESS-ARRAY ( i1 i2 ... iX a-addr1 --- a-addr2 n )
at a-addr1 a list of numbers as stored by BUILD-ARRAY is expected.
Multiplies and adds actual indices i1...iX with stored upper bounds
n1...nX giving n, the linear offset of the element specified by
i1...iX.
a-addr2 is `a-addr1 X CELLS +', i.e. points just after the stored list
of upper bounds.


: 0<= ( n --- flag )
flag is true (-1) if n is less than or equal to 0, false (0) otherwise.


: 0>= ( n --- flag )
flag is true (-1) if n is greater than or equal to 0, false (0) otherwise.


: <= ( n1 n2 --- flag )
flag is true (-1) if n1 is less than or equal to n2, false (0) otherwise.


: >= ( n1 n2 --- flag )
flag is true (-1) if n1 is greater than or equal to n2, false (0) otherwise.


: U<= ( u1 u2 --- flag )
flag is true (-1) if u1 is less than or equal to u2, false (0) otherwise.


: U>= ( u1 u2 --- flag )
flag is true (-1) if u1 is greater than or equal to u2, false (0) otherwise.


: UMAX ( u1 u2 --- u3 )
u3 is the greater of u1 and u2.


: UMIN ( u1 u2 --- u3 )
u3 is the lesser of u1 and u2.


: SOURCE-LINE ( --- n )
n is the line of source currently interpreted when loading a text file
with INCLUDED or when loading a block it's the current input position
divided by 64. If not loading from a block or a file, n is 0.


: POCKET ( n --- addr u )
returns the string stored in the n-th buffer used by S" or C". S" and
C" use a set of buffers in cyclical manner.


: LAST ( --- c-addr )
returns the address of the count byte of the name of the most recently
defined word. If the compilation word list has changed since the most
recent definition this doesn't affect LAST. If the most recent
definition has been deleted meanwhile, then the address returned by
LAST is invalid. See CREATE, LATEST.


: TOPMOST ( wid --- a-addr )
in a-addr points to: a pointer to the count byte of the topmost
definition in the given wordlist. See LATEST, WL-HASH.


: WL-HASH ( c-addr n1 --- n2 )
n2 is a hash code formed from the string at c-addr with length n1.
This is the hash function used to select one of multiple threads
(linked lists of definitions) in the dictionary. Words are stored in
and must be searched in the thread computed by this function. Of
course FIND hides these details. WL-HASH is provided in case you want
to define your own kind of FIND.


: WWORDS ( "<spaces>pattern" --- )
Parses the input for a space-delimited search pattern. Displays all
words from the first word list in the search order that match this
pattern. Form patterns with wildcards '?' and '*' like this:
	* matches any sequence of characters
	? matches any single character
	\ quotes * and ?
	any other character matches this character
Examples:
	WWORDS ??	displays all words with two letters
	WWORDS E*	displays all words beginning with E
	WWORDS F*A*	displays all words beginning with F having
			an A in the name.
	WWORDS *\?	displays all words ending with '?'.


: W@ ( a-addr --- n )
n is the 16 bit integer stored at a-addr.


: W! ( x a-addr --- )
stores the least significant 16 bit of x at a-addr.


: W+! ( x a-addr --- )
adds the least significant 16 bit of x to the 16 bit integer stored at
a-addr.


: (FORGET) ( addr --- )
deletes all words stored above addr from the dictionary.


: TAB ( n --- )
displays at least one and as many spaces as neccessary to make the
column number -- stored in the variable OUT -- divisible by n.


: BACKSPACE ( --- )
